As computers and computer technology become more complex, a continuing need exists for documentation to assist programmers, service personnel, and other users in understanding various computer technologies. Computer documentation may include practically any information about the hardware and/or software of a computer.
For example, one predominant use of computer documentation is in the area of documenting computer programming languages. Both the underlying language syntax, and programs written in a particular language, often need to be documented to assist programmers in developing, debugging and using various computer programs written in a particular language. Furthermore, the increasingly-common practice of reusing pre-existing program code in new computer programs has necessitated that much of the program code being developed today be well documented for the benefit of other computer programmers. Advancements in object-oriented technology, for example, have enabled computer programmers to assemble complex computer programs using a multitude of pre-existing software components, which often minimizes the amount of custom code that needs to be generated by a programmer to interface the pre-existing components together. Countless hours and expenses that would otherwise be required to develop a program from scratch can be saved through the use of reusable software components.
Before a reusable component can be incorporated into a particular computer application, however, a programmer is required to understand the various operations and data supported by that component. Access to documentation about the capabilities and limitations of reusable components is therefore often a key to a programmer's ability to efficiently incorporate reusable components in a computer application.
Early attempts at documenting computer software were often limited to the insertion of text comments into the actual source code for a particular program or program component. For more complex projects, documentation could be generated manually by the developer or by another individual as a separate document from the source code. In many instances, the generation of documentation for a computer program required nearly as much effort as the development of the program itself.
Later, document generation tools were developed to assist programmers in automatically generating documentation for computer programs and components developed by those programmers. For example, for the Java program environment, a document generation tool known as Javadoc was developed to automatically generate documentation files for Java program entities such as classes and the like.
Using the Javadoc tool, programmers are permitted to insert markup tags in source code using well-defined conventions. Then, by passing the annotated or marked up source code through the Javadoc tool, a set of standardized documentation files may be generated. Moreover, the documentation files generated by the Javadoc tool are typically arranged into a well-accepted directory format containing, in addition to the generated documentation files, a number of standardized files used to provide a consistent look and feel to a user viewing the documentation files. Additional value-added features, such as alphabetical indices, version information, class hierarchy information, class-use information, and table of content information are also automatically generated by the Javadoc tool.
Consistent with the Java programming language, program code is often organized into classes, which are used as templates to instantiate Java-compatible objects. Classes are typically organized into packages with other related classes. Moreover, related packages are typically collected together to form collections commonly referred to as Application Programming Interface (API) sets.
The Javadoc tool typically generates documentation files grouped by class, package, and ultimately under a single API set. Supplemental material such as index files, class hierarchy tree files, overview files, class-use files, etc. are generated from all of the program code collected under a given API set.
Moreover, while other file formats are supported, Javadoc documentation files are typically formatted in Hypertext Markup Language (HTML), with hypertext links embedded in the files to permit a user to jump from documentation file to documentation file in a fast and intuitive manner. Also, by generating documentation files in this manner, users are able to view the documentation files using a conventional HTML-compatible web browser.
In many instances, the Javadoc tool generates a collection of HTML files that are displayed in a plurality of panes or frames, and that function as navigation files to assist a user in jumping between various packages and classes collected under a given API set. Typically, a main frame is displayed at the right side of a window and is used to display most of the relevant documentation information. To the left of the main frame are two navigation frames, including a package navigation frame stacked on top of a class navigation frame. The package navigation frame displays a package navigation file including a plurality of package links that identify each package in the API set. The class navigation frame displays a class navigation file including a plurality of class links identifying each class in a given package. Thus, through selection of a particular package link in the package navigation file, the class navigation frame is updated to display a list of classes included in the selected package. Then, by selecting a class link from the class navigation frame, documentation associated with the selected class is displayed in the main frame of the window.
While the conventional Javadoc layout substantially simplifies user access to Java-related documentation, a problem still exists due to the fact that many programmers rely on a number of different API sets when constructing Java-compatible programs. For example, a typical Java developer may need the documentation for the core Java Developer Kit (JDK) API set, several optional packages, an XML parser, an API built on top of the XML parser, and any relevant build tool. Typically, however, the documentation for all of these API sets is separately generated and stored by the Javadoc tool, so a user is left to manually find and access the documentation for a given API set.
Moreover, with the rise of open source and enterprise frameworks, programmers are often required to interface with more and more code pieces that they did not originally write, making the ability to quickly find the documentation for these API sets even more cumbersome. While Javadoc-generated documentation files exist for many of these API sets, however, there is no structured manner for collecting the documentation for multiple APIs in one organized and usable accessible system.
Some programmers may attempt to remedy this problem individually by creating a personal portal web page, or by creating bookmarks that may be used to open up the documentation files for specific API sets. However, as discussed above, one of the advantages of Javadoc is the degree of cross-referencing and indexing that takes place during the generation of documentation files. With no integration of documentation files from multiple API sets, the index files, the class-use files, class hierarchy files, etc. do not span multiple API sets, so if a user is attempting to find documentation regarding a particular program entity, but that user is unsure of which API set that entity resides within, the user is left to manually search the documentation files for multiple API sets to attempt to find the relevant information.
Therefore, a significant need exists in the art for a manner of better organizing the documentation files for multiple API sets.